/**   
* @Title: ActionMode.java 
* @Package com.actionbarsherlock.view 
* @Description: 
*			声明:
*			1)掌控校园是本人的大学的创业作品,也是本人的毕业设计
*			2)本程序尚未进行开放源代码,所以禁止组织或者是个人泄露源码,否则将会追究其刑事责任
*			3)编写本软件,我需要感谢彭老师以及其他鼓励和支持我的同学以及朋友
*			4)本程序的最终所有权属于本人	
* @author  张雷 794857063@qq.com
* @date 2013-11-14 19:34:24 
* @version V1.0   
*/

package com.actionbarsherlock.view;

import android.view.View;

// TODO: Auto-generated Javadoc
/**
 * Represents a contextual mode of the user interface. Action modes can be used
 * for modal interactions with content and replace parts of the normal UI until
 * finished. Examples of good action modes include selection modes, search,
 * content editing, etc.
 */
public abstract class ActionMode {
	
	/** The m tag. */
	private Object mTag;

	/**
	 * Set a tag object associated with this ActionMode.
	 * 
	 * <p>
	 * Like the tag available to views, this allows applications to associate
	 * arbitrary data with an ActionMode for later reference.
	 * 
	 * @param tag
	 *            Tag to associate with this ActionMode
	 * 
	 * @see #getTag()
	 */
	public void setTag(Object tag) {
		mTag = tag;
	}

	/**
	 * Retrieve the tag object associated with this ActionMode.
	 * 
	 * <p>
	 * Like the tag available to views, this allows applications to associate
	 * arbitrary data with an ActionMode for later reference.
	 * 
	 * @return Tag associated with this ActionMode
	 * 
	 * @see #setTag(Object)
	 */
	public Object getTag() {
		return mTag;
	}

	/**
	 * Set the title of the action mode. This method will have no visible effect
	 * if a custom view has been set.
	 * 
	 * @param title
	 *            Title string to set
	 * 
	 * @see #setTitle(int)
	 * @see #setCustomView(View)
	 */
	public abstract void setTitle(CharSequence title);

	/**
	 * Set the title of the action mode. This method will have no visible effect
	 * if a custom view has been set.
	 * 
	 * @param resId
	 *            Resource ID of a string to set as the title
	 * 
	 * @see #setTitle(CharSequence)
	 * @see #setCustomView(View)
	 */
	public abstract void setTitle(int resId);

	/**
	 * Set the subtitle of the action mode. This method will have no visible
	 * effect if a custom view has been set.
	 * 
	 * @param subtitle
	 *            Subtitle string to set
	 * 
	 * @see #setSubtitle(int)
	 * @see #setCustomView(View)
	 */
	public abstract void setSubtitle(CharSequence subtitle);

	/**
	 * Set the subtitle of the action mode. This method will have no visible
	 * effect if a custom view has been set.
	 * 
	 * @param resId
	 *            Resource ID of a string to set as the subtitle
	 * 
	 * @see #setSubtitle(CharSequence)
	 * @see #setCustomView(View)
	 */
	public abstract void setSubtitle(int resId);

	/**
	 * Set a custom view for this action mode. The custom view will take the
	 * place of the title and subtitle. Useful for things like search boxes.
	 * 
	 * @param view
	 *            Custom view to use in place of the title/subtitle.
	 * 
	 * @see #setTitle(CharSequence)
	 * @see #setSubtitle(CharSequence)
	 */
	public abstract void setCustomView(View view);

	/**
	 * Invalidate the action mode and refresh menu content. The mode's
	 * {@link ActionMode.Callback} will have its
	 * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called. If
	 * it returns true the menu will be scanned for updated content and any
	 * relevant changes will be reflected to the user.
	 */
	public abstract void invalidate();

	/**
	 * Finish and close this action mode. The action mode's
	 * {@link ActionMode.Callback} will have its
	 * {@link Callback#onDestroyActionMode(ActionMode)} method called.
	 */
	public abstract void finish();

	/**
	 * Returns the menu of actions that this action mode presents.
	 * 
	 * @return The action mode's menu.
	 */
	public abstract Menu getMenu();

	/**
	 * Returns the current title of this action mode.
	 * 
	 * @return Title text
	 */
	public abstract CharSequence getTitle();

	/**
	 * Returns the current subtitle of this action mode.
	 * 
	 * @return Subtitle text
	 */
	public abstract CharSequence getSubtitle();

	/**
	 * Returns the current custom view for this action mode.
	 * 
	 * @return The current custom view
	 */
	public abstract View getCustomView();

	/**
	 * Returns a {@link MenuInflater} with the ActionMode's context.
	 * 
	 * @return the menu inflater
	 */
	public abstract MenuInflater getMenuInflater();

	/**
	 * Returns whether the UI presenting this action mode can take focus or not.
	 * This is used by internal components within the framework that would
	 * otherwise present an action mode UI that requires focus, such as an
	 * EditText as a custom view.
	 * 
	 * @return true if the UI used to show this action mode can take focus
	 * @hide Internal use only
	 */
	public boolean isUiFocusable() {
		return true;
	}

	/**
	 * Callback interface for action modes. Supplied to
	 * {@link View#startActionMode(Callback)}, a Callback configures and handles
	 * events raised by a user's interaction with an action mode.
	 * 
	 * <p>
	 * An action mode's lifecycle is as follows:
	 * <ul>
	 * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial
	 * creation</li>
	 * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation
	 * and any time the {@link ActionMode} is invalidated</li>
	 * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a
	 * contextual action button is clicked</li>
	 * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode
	 * is closed</li>
	 * </ul>
	 */
	public interface Callback {
		/**
		 * Called when action mode is first created. The menu supplied will be
		 * used to generate action buttons for the action mode.
		 * 
		 * @param mode
		 *            ActionMode being created
		 * @param menu
		 *            Menu used to populate action buttons
		 * @return true if the action mode should be created, false if entering
		 *         this mode should be aborted.
		 */
		public boolean onCreateActionMode(ActionMode mode, Menu menu);

		/**
		 * Called to refresh an action mode's action menu whenever it is
		 * invalidated.
		 * 
		 * @param mode
		 *            ActionMode being prepared
		 * @param menu
		 *            Menu used to populate action buttons
		 * @return true if the menu or action mode was updated, false otherwise.
		 */
		public boolean onPrepareActionMode(ActionMode mode, Menu menu);

		/**
		 * Called to report a user click on an action button.
		 * 
		 * @param mode
		 *            The current ActionMode
		 * @param item
		 *            The item that was clicked
		 * @return true if this callback handled the event, false if the
		 *         standard MenuItem invocation should continue.
		 */
		public boolean onActionItemClicked(ActionMode mode, MenuItem item);

		/**
		 * Called when an action mode is about to be exited and destroyed.
		 * 
		 * @param mode
		 *            The current ActionMode being destroyed
		 */
		public void onDestroyActionMode(ActionMode mode);
	}
}